docs: add troubleshooting guide with 10 documented issues - #757

🏁 Script executed:

rg -n 'soroban-cli|stellar-cli|soroban |stellar ' --glob '!node_modules/**' .

Repository: ritik4ever/stellar-goal-vault

Length of output: 3576

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== docs/TROUBLESHOOTING.md lines 1-60 =="
cat -n docs/TROUBLESHOOTING.md | sed -n '1,60p'

echo
echo "== scripts/deploy.sh CLI checks/invocations =="
cat -n scripts/deploy.sh | sed -n '30,90p'

echo
echo "== README stellar invocations =="
cat -n README.md | sed -n '60,170p'

echo
echo "== package/tooling references =="
for f in package.json Cargo.toml Cargo.lock justfile README.md; do
  [ -f "$f" ] && { echo "--- $f"; sed -n '1,140p' "$f"; }
done

Repository: ritik4ever/stellar-goal-vault

Length of output: 17565

🌐 Web query:

Stellar CLI soroban-cli 20.0.0 install cargo install --locked version 20.0.0 soroban-cli command name

💡 Result:

To install the CLI tool for Stellar and Soroban development, the current standard command is cargo install --locked stellar-cli [1][2][3]. The crate formerly known as soroban-cli has been renamed to stellar-cli [1][3]. While you may see references to installing soroban-cli in older documentation or specific legacy versions (such as v20.x), the official and current package name used for installation is stellar-cli [1][4][3]. Regarding your specific query: 1. Command Name: Once installed, the command used to interact with the tool is stellar [5][6]. Older versions of the tool were sometimes referred to or invoked as soroban, but modern versions use the stellar command [1][5][6]. 2. Installation for version 20.0.0: If you specifically require version 20.0.0 for legacy compatibility, you would typically use cargo install --locked stellar-cli --version 20.0.0. However, it is strongly recommended to use the latest version available on crates.io to ensure compatibility with current network protocols [4]. In summary, use stellar-cli as the package name for cargo install and stellar as the command line interface [2][3][6].

Citations:

• 1: https://github.com/stellar/soroban-cli
• 2: https://developers.stellar.org/docs/tools/cli/install-cli
• 3: https://github.com/stellar/stellar-cli
• 4: https://crates.io/crates/soroban-cli/20.1.1
• 5: https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup
• 6: https://github.com/stellar/soroban-examples/blob/main/FULL_HELP_DOCS.md

🌐 Web query:

Stellar CLI 27.0 stellar network add global option network passphrase

💡 Result:

In the Stellar CLI, --network-passphrase is a standard option used to specify the network passphrase required for signing transactions [1][2][3]. It is categorized as an RPC-related option that is available for many commands that interact with the network [3]. Key details regarding this option include: Precedence and Behavior: 1. Named Network Priority: When you use the --network flag, the Stellar CLI resolves the network configuration from your on-disk settings [1][4]. Recent updates have established that a named network takes precedence over any --network-passphrase or --rpc-url provided via flags or environment variables [4]. 2. Overrides: If you do not use a named network, you can manually provide the --network-passphrase. For specific diagnostic commands, such as stellar network root-account, the --network-passphrase flag can be used to override other configured settings to derive root account keys [5]. 3. Configuration: While you can provide the passphrase as a flag, the recommended practice for general use is to configure named networks using the stellar network add command, which stores the network passphrase and RPC URL associated with an alias [3]. Usage: To use the option, append it to your command: stellar --network-passphrase "YOUR_PASSPHRASE" Note: Ensure you are using the correct passphrase for the intended network (e.g., the public network or a test network), as using an incorrect one will cause transaction authentication errors [6]. If you have a named network configured, you generally do not need to manually enter the passphrase [7][3].

Citations:

• 1: https://developers.stellar.org/docs/tools/cli/stellar-cli
• 2: https://github.com/stellar/stellar-cli/blob/main/FULL%5FHELP%5FDOCS.md
• 3: https://deepwiki.com/stellar/stellar-docs/7.1-stellar-cli-reference
• 4: Make --network take precedence over rpc-url/passphrase env vars stellar/stellar-cli#2579
• 5: Add stellar network root-account command stellar/stellar-cli#2402
• 6: https://developers.stellar.org/docs/tools/quickstart/network-modes
• 7: Use alias for network stellar/stellar-cli#1610

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== docs/TROUBLESHOOTING.md lines =="
if [ -f docs/TROUBLESHOOTING.md ]; then
  nl -ba docs/TROUBLESHOOTING.md | sed -n '1,80p'
else
  echo "docs/TROUBLESHOOTING.md not found"
fi

echo
echo "== Find Freighter/network troubleshooting references =="
rg -n -i "Freighter|Connection rejected|not installed|connection request|locked|stellar network add|soroban-testnet.stellar.org|testnet" -S . --glob '!node_modules/**' --glob '!target/**' --glob '!dist/**' | head -200

Repository: ritik4ever/stellar-goal-vault

Length of output: 243

🏁 Script executed:

#!/bin/sh
set -euo pipefail

echo "== docs/TROUBLESHOOTING.md lines =="
if [ -f docs/TROUBLESHOOTING.md ]; then
  cat -n docs/TROUBLESHOOTING.md | sed -n '1,80p'
else
  echo "docs/TROUBLESHOOTING.md not found"
fi

echo
echo "== Find Freighter/network troubleshooting references =="
grep -RIn -E "Freighter|Connection rejected|not installed|connection request|locked|stellar network add|soroban-testnet.stellar.org|testnet" . --exclude-dir=node_modules --exclude-dir=target --exclude-dir=dist | head -200 || true

Repository: ritik4ever/stellar-goal-vault

Length of output: 50386

🏁 Script executed:

#!/bin/sh
set -euo pipefail

echo "== docs/TROUBLESHOOTING.md lines 1-80 =="
awk '1==NR && NR<=80' docs/TROUBLESHOOTING.md | cat -n

echo
echo "== Target references in tracked/source files only =="
git ls-files | grep -E '(^docs/TROUBLESHOOTING\.md$|^docs/|^\.github/|src/|package.json|README\.md)' | while read -r f; do
  grep -RInEi "Freighter|connection rejected|not installed|connection request|locked|stellar network add|soroban-testnet.stellar.org|testnet" "$f" 2>/dev/null || true
done | head -200

Repository: ritik4ever/stellar-goal-vault

Length of output: 12199

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== docs/TROUBLESHOOTING.md excerpt =="
if [ -f docs/TROUBLESHOOTING.md ]; then
  cat -n docs/TROBLESHOOTING.md | sed -n '1,90p' || true
  echo
  cat -n docs/TROUBLESHOOTING.md | sed -n '1,90p' || true
fi

echo
echo "== README.md deployment/env references =="
if [ -f README.md ]; then
  rg -n -i "CONTRACT_ID|contract deploy|soroban contract deploy|\\.env|backend/.env|environment" README.md -C 3 || true
fi

echo
echo "== backend env files =="
fd -a '^(\.env|.*\.env.*)$' backend . 2>/dev/null | sed 's#^\./##' | head -100
for f in $(fd '^(\.env|.*\.env.*)$' backend . 2>/dev/null | head -20); do
  echo "--- $f"
  sed -n '1,200p' "$f" | head -80 || true
done

echo
echo "== occurrences of generated contract file and CONTRACT_ID =="
rg -n "backend/\.env\.contract|#.*CONTRACT_ID|CONTRACT_ID=|contract deploy|contract-id|contract ID" -S . || true

Repository: ritik4ever/stellar-goal-vault

Length of output: 12170

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== scripts/deploy.sh relevant deployment flow =="
cat -n scripts/deploy.sh | sed -n '1,130p'

echo
echo "== DEPLOYMENT.md contract deployment section =="
cat -n DEPLOYMENT.md | sed -n '40,70p'

echo
echo "== local deploy output format evidence from scripts =="
python3 - <<'PY'
from pathlib import Path
scripts = [Path("scripts/deploy.sh"), Path("scripts/benchmark.sh")]
for p in scripts:
    if p.exists():
        text = p.read_text()
        if "DEPLOY_OUTPUT=$(soroban contract deploy" in text or "export CONTRACT_ID=$(cat contracts/contract_id.txt)" in text:
            print(f"\n-- {p} --")
            for i,line in enumerate(text.splitlines(), 1):
                if "contract deploy" in line or "DEPLOY_OUTPUT" in line or "grep -oE" in line or "CONTRACT_ID=$" in line or "CONTRACT_ID=" in line:
                    print(f"{i}: {line}")
PY

Repository: ritik4ever/stellar-goal-vault

Length of output: 5998

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Locate troubleshooting file and reference documentation snippets:\n'
git ls-files | grep -E '(^|/)TROUBLESHOOTING\.md$|README|CONTRIBUTING' || true
if [ -f docs/TROUBLESHOOTING.md ]; then
  sed -n '60,90p' docs/TROUBLESHOOTING.md | cat -n
fi

printf '\nSearch for getNetwork examples and curl diagnostics in repo:\n'
rg -n 'getNetwork|soroban-testnet|Timeout waiting for transaction|rpc|jsonrpc' docs README.md . 2>/dev/null | head -n 80 || true

Repository: ritik4ever/stellar-goal-vault

Length of output: 50388

🌐 Web query:

Stellar Soroban RPC getNetwork example curl Content-Type application/json

💡 Result:

To query the Stellar RPC (formerly Soroban-RPC) for network information using the getNetwork method, use an HTTP POST request with a Content-Type of application/json [1][2][3]. The method does not require any parameters [1][4]. Below is an example curl command. Replace <RPC_URL> with the endpoint of the Stellar RPC node you are accessing (e.g., a public provider or your own instance): curl --request POST \ --url <RPC_URL> \ --header 'Content-Type: application/json' \ --data '{ "jsonrpc": "2.0", "id": 1, "method": "getNetwork", "params": [] }' The Stellar RPC follows the JSON-RPC 2.0 specification [5][6]. The getNetwork method returns general information about the network, including the passphrase, the current protocol version, and an optional friendbot URL [1][2][4]. Top Results: [7][1][2][3][4]

Citations:

• 1: https://docs.uniblock.dev/reference/jsonrpc-docs/stellar-soroban/stellar/get-network
• 2: https://docs.validationcloud.io/v1/stellar/stellar-rpc-formerly-soroban-api/getnetwork
• 3: https://developers.stellar.org/docs/data/apis/rpc
• 4: https://www.alchemy.com/docs/chains/stellar/stellar-api-endpoints/get-network.md
• 5: https://developers.stellar.org/docs/data/apis/rpc/api-reference/structure/json-rpc
• 6: https://developers.stellar.org/docs/data/apis/migrate-from-horizon-to-rpc
• 7: https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getNetwork

🌐 Web query:

developers.stellar.org getNetwork curl example Content-Type application/json Soroban RPC

💡 Result:

To query the getNetwork method on a Stellar RPC server, you must send a POST request with a Content-Type of application/json [1][2]. The request body must be a JSON-RPC 2.0 object specifying the method as getNetwork [1][2]. Below is a standard curl example for the getNetwork method: curl -X POST \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "getNetwork" }' \ https://soroban-testnet.stellar.org Note that Stellar RPC was formerly known as Soroban-RPC [3]. When using this command, replace the URL (https://soroban-testnet.stellar.org) with the appropriate RPC endpoint you are targeting [3][1]. The getNetwork method does not require any additional parameters [1].

Citations:

• 1: https://www.quicknode.com/docs/stellar/getNetwork
• 2: https://docs.validationcloud.io/v1/stellar/stellar-rpc-formerly-soroban-api/getnetwork
• 3: https://developers.stellar.org/docs/data/apis/rpc